DigiLocker Fetch PAN and Driving Licence API

The following document highlights the details of the DigiLocker Fetch PAN and Driving Licence API.

API Description

Objective

The DigiLocker Fetch PAN and Driving Licence API retrieves the driving license and the Permanent Account Number (PAN) details of the customer from their DigiLocker account.

Note

This is available only if the driving license and the PAN details are issued in the customer's DigiLocker account.

Input	Output
A unique reference identifier	The driving license and PAN details of the customer in a JSON response, including their name, date of birth, address, photo, and other relevant information

API URL

https://ind-verify.hyperverge.co/api/digilocker/docDetails

API Endpoint

docDetails

Overview

The DigiLocker Fetch PAN and Driving Licence API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Optional	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the DigiLocker Fetch PAN and Driving Licence API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
referenceId	Mandatory	string	The unique reference identifier generated in the initial request	Not Applicable	Not Applicable
pan	Optional	string	The parameter that confirms if the API should fetch the PAN details from the DigiLocker account	yes / no	Not Applicable
dl	Optional	string	The parameter that confirms if the API should fetch the Driving License (DL) details from the DigiLocker account	yes / no	Not Applicable
panFile	Optional	string	The parameter, when set to yes, controls whether the PAN file should be fetched from the user's DigiLocker account. The pan file will be returned in the form of an s3 url that will be valid for 15 minutes	yes / no	Not Applicable
dlFile	Optional	string	The parameter, when set to yes, controls whether the driving license file should be fetched from the user's Digilocker account. The DL file will be returned in the form of an s3 url that will be valid for 15 minutes	yes / no	Not Applicable
blockMinors	Optional	string	The parameter that controls whether a 400 response is returned if the DigiLocker account belongs to a minor. When set to "yes", the API returns a 400 response	Not Applicable	Not Applicable
returnAllFieldsFromDigilocker	Optional	string	The parameter that controls whether all fields for PAN and DL are retrieved from the DigiLocker account. When set to "yes", the API retrieves all available fields	yes / no	no
useV2StorageLocation	Optional	string	The parameter that enables dashboard visibility. When set to "yes", you can view the data in the dashboard	yes / no	no
enableRetry	Optional	string	The parameter that controls retry behavior. When set to "yes", the API retries the same request three times before generating a response	yes / no	no
returnFileNotFoundError	Optional	string	The parameter that controls whether a file not found error is returned. When set to "yes", returns file not found error if failed to fetch pan/dl files after 3 retries. Note: This parameter should be passed only when enableRetry is set to "yes"	Not Applicable	Not Applicable
returnSummary	Optional	string	The parameter that controls whether a summary key is returned in the response. When set to "yes", returns summary key in response	yes / no	no

Request

The following code snippet demonstrates a standard curl request for the DigiLocker Fetch PAN and Driving Licence API:

curl --location --request POST 'https://ind-verify.hyperverge.co/api/digilocker/docDetails' \
--header 'Content-Type: application/json' \
--header 'appID: <Enter_the_HyperVerge_appId>'\
--header 'appKey: <Enter_the_HyperVerge_appKey>'\
--header 'transactionID: <Enter_the_HyperVerge_transactionID>' \
--data-raw '{
    "referenceId": "<Reference_ID>",
    "pan": "<yes_or_no>",
    "dl": "<yes_or_no>",
    "panFile": "<yes_or_no>",
    "dlFile": "<yes_or_no>",
    "panXMLFile": "<yes_or_no>"
    "dlXMLFile": "<yes_or_no>"
    "returnAllFieldsFromDigilocker": "<yes_or_no>",
    "useV2StorageLocation": "<yes_or_no>",
    "enableRetry": "<yes_or_no>"
}'

Success Responses

The following code snippets demonstrate success responses from the DigiLocker Fetch PAN and Driving Licence API:

Retrieve both PAN and DL

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "code": "ALL_FOUND",
        "docs_found": [
            "pan",
            "dl"
        ],
        "details": [
            {
                "doc_type": "",
                "pan": "",
                "name": "",
                "dob": ""
            },
            {
                "doc_type": "",
                "dl": "",
                "name": "",
                "dob": "",
                "address": "[object Object],, [object Object]",
                "photo": "base64"
            }
        ]
    }
}

Retrieve Only Driving License

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "code": "DL_FOUND",
    "docs_found": [
      "dl"
    ],
    "details": [
      {
        "doc_type": "driving_licence",
        "dl": "string",
        "name": "string",
        "dob": "string",
        "gender": "string",
        "photo": "string",
        "address": {
          "present": "string",
          "permanent": "string"
        },
        "issue_date": "string",
        "valid_upto": "string",
        "authorised_categories": [
          "string"
        ]
      }
    ]
  }
}

Retrieve Only PAN

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "code": "PAN_FOUND",
    "docs_found": [
      "pan"
    ],
    "details": [
      {
        "pan": "string",
        "name": "String",
        "dob": "String",
        "gender": "String",
        "last_verified": "timestamp"
      }
    ]
  }
}

Retrieve All Fields

The following is a response when you set the returnAllFieldsFromDigilocker parameter value to "yes".

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "code": "PAN_FOUND",
    "docs_found": [
      "pan",
      "dl"
    ],
    "details": [
      {
        "doc_type": "pan",
        "pan": "",
        "name": "",
        "dob": "",
        "file": "",
        "gender": "",
        "swd": "",
        "swd_indicator": "",
        "marital_status": "",
        "religion": "",
        "phone": "",
        "email": "",
        "issued_by_org": {},
        "issued_at": "",
        "issue_date": "",
        "verified_on": "",
        "valid_from_date": ""
      },
      {
        "doc_type": "dl",
        "dl": "",
        "name": "",
        "dob": "",
        "photo": "",
        "age": "",
        "gender": "",
        "swd": "",
        "swd_indicator": "",
        "marital_status": "",
        "religion": "",
        "phone": "",
        "email": "",
        "issued_by_org": {},
        "issued_at": "",
        "issue_date": "",
        "expiry_date": "",
        "valid_from_date": "",
        "categories": {}
      }
    ]
  }
}

No Documents Found

The following is a response when no documents are found in the user's DigiLocker Account:

{
     "status": "success",
     "statusCode": "200",
     "result": {
         "code": "NO_DOC_FOUND",
         "docs_found": [],
         "details": []
     }
 }

Success Response Details

The following table outlines the details of the success response from the DigiLocker Fetch PAN and Driving Licence API:

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code for the response
result	object	The JSON object containing the driving license and PAN details
result.code	string	The code indicating which documents were found (e.g., "ALL_FOUND", "PAN_FOUND", "DL_FOUND", "NO_DOC_FOUND")
result.docs_found	array	An array of document types found (e.g., ["pan"], ["dl"], ["pan", "dl"])
result.details	array	An array of objects containing the document details
result.details[].doc_type	string	The type of document (e.g., "pan", "driving_licence", "dl")
result.details[].pan	string	The PAN number of the customer
result.details[].dl	string	The driving license number of the customer
result.details[].name	string	The name of the customer
result.details[].dob	string	The date of birth of the customer
result.details[].gender	string	The gender of the customer
result.details[].photo	string	The base64 string of the customer's profile photo (for DL)
result.details[].address	string or object	The address of the customer (can be a string or an object with "present" and "permanent" fields for DL)
result.details[].file	string	The S3 URL for the document file
result.details[].issue_date	string	The issue date of the document
result.details[].valid_upto	string	The validity date of the driving license
result.details[].authorised_categories	array	An array of authorized vehicle categories for the driving license

Error Responses

The following are some error responses from the DigiLocker Fetch PAN and Driving Licence API:

File Not Fetched

This error is returned when the enableRetry parameter is enabled in the request, in the scenario when the files are not fetched even after multiple retries.

{
     "status": "failure",
     "statusCode": "400",
     "error": {
         "code": "ER_FILE_NOT_FETCHED",
         "message": "could not fetch file from digilocker."
     }
 }

User Consent Missing

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_USER_DIGILOCKER_ACCESS_CONSENT_MISSING",
    "message": "consent not provided by user to access digilocker"
  }
}

Missing Mandatory Reference ID Input

{
     "status": "failure",
     "statusCode": "400",
     "error": {
         "code": "ER_REQ_VALIDATE",
         "message": "referenceId is required"
     }
}

Invalid Reference ID Input

{
     "status": "failure",
     "statusCode": "400",
     "error": {
         "code": "ER_INVALID_REFID",
         "message": "Please try verifying the refId"
     }
}

PAN Name Mismatch

{
    "status": "failure",
    "statusCode": "400",
    "error": {
        "code": "ER_PAN_NAME_MISMATCH",
        "message": "PAN Name does not match with Digilocker data"
    }
}

Minor Account

The following code snippet is returned when the parameter blockMinors is enabled in the request body:

{
     "status": "failure",
     "statusCode": "400",
     "error": {
         "code": "ER_MINOR_ACCOUNT",
         "message": "Entered details belongs to a minor."
     }
}

No Record for PAN input

{
     "status": "failure",
     "statusCode": "422",
     "error": {
         "code": "ER_PAN_DATA_NOT_AVAILABLE",
        "message": "No data found for the given pan"
     }
}

No Record for Driving License input

{
     "status": "failure",
     "statusCode": "422",
     "error": {
         "code": "ER_DL_DATA_NOT_AVAILABLE",
        "message": "No data found for the given DL"
     }
}

Server Error

{
     "status": "failure",
     "statusCode": "500",
     "error": {
         "code": "ER_SERVER",
         "message": "Something went wrong"
     }
}

DigiLocker Error

{
     "status": "failure",
     "statusCode": "503",
     "error": {
         "code": "ER_DIGILOCKER_REPO_SERVICE_RESPERROR",
         "message": "Error Connecting to digilocker. Please try again after sometime"
     }
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	referenceId is required	The mandatory referenceId parameter is missing from the request	Provide valid referenceId in the request
400	pan is required	The mandatory pan parameter is missing from the request	Provide valid pan parameter in the request
400	Please try verifying the refId	The provided referenceId is invalid	Verify and provide a valid referenceId
400	could not fetch file from digilocker.	Files could not be fetched from DigiLocker even after multiple retries (when enableRetry is set to "yes")	Please try again after sometime or contact the HyperVerge team
400	consent not provided by user for the document.	The user rejected consent to access their document from DigiLocker	Please ensure user provides consent or try again
400	Entered details belongs to a minor.	The entered details belong to a minor account	Please ensure the user is not a minor or contact the HyperVerge team
400	PAN Name does not match with Digilocker data	The PAN name does not match the associated name in the user's DigiLocker account	Please ensure the PAN name matches the Aadhaar name in the user's DigiLocker account
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Provide valid appId and appKey credentials in the request
422	No data found for the given pan	No PAN data found for the provided input in the user's DigiLocker account	Please ensure the user has PAN document in their DigiLocker account
422	No data found for the given DL	No Driving License data found for the provided input in the user's DigiLocker account	Please ensure the user has Driving License document in their DigiLocker account
500	Something went wrong	There was an error with HyperVerge's server	Please check the request headers or contact the HyperVerge team for resolution
503	Error Connecting to digilocker. Please try again after sometime	DigiLocker repository service returned an error (ER_DIGILOCKER_REPO_SERVICE_RESPERROR); connection to DigiLocker failed.	Retry the request after some time or contact the HyperVerge team if the issue persists